…on A rewrite

normalize-result, consume-adapter-stream, tool-dispatch were extracted to
core/agent/ but agents.ts still imported them from plugins/agents/. Update
the import paths to match the final file locations.

Flips the layering: agent types, helpers, and the standalone runner now
live in core/agent/ instead of plugins/agents/. The HTTP-facing agents()
plugin still owns its routes/streaming/threads but no longer re-exports
framework primitives that peer plugins depend on.

Moved (with git mv to preserve history):
- plugins/agents/{types,from-plugin,build-toolkit,toolkit-resolver,
  consume-adapter-stream,normalize-result,tool-dispatch,system-prompt,
  load-agents}.ts -> core/agent/
- plugins/agents/tools/{tool,define-tool,function-tool,hosted-tools,
  sql-policy,json-schema,index}.ts -> core/agent/tools/
- core/{run-agent,create-agent-def}.ts -> core/agent/{run-agent,create-agent}.ts
- 14 corresponding test files -> core/agent/tests/

Stayed in plugins/agents/ (HTTP/route concerns):
- agents.ts, event-channel.ts, event-translator.ts, tool-approval-gate.ts,
  thread-store.ts, schemas.ts, defaults.ts, manifest.json, index.ts

Updated imports across analytics, files, genie, lakebase to source from
core/agent/ directly. plugins/agents/index.ts stays as a back-compat
barrel that re-exports the moved primitives, so the public package
surface (@databricks/appkit) is byte-identical.

Verified: tsc --noEmit clean, 1581/1581 appkit tests pass.

Extracts `composePromptForAgent` + `normalizeAutoInherit` into
plugins/agents/prompt.ts and `printRegistry` into
plugins/agents/registry-printer.ts. These were free-function helpers at
the bottom of agents.ts with no dependency on plugin state — pure
candidates for extraction.

Also opens the door for the bigger split (route handlers and
`_streamAgent`/`runSubAgent` extracted into routes/*.ts and
tool-execution.ts) by relaxing the access modifier on plugin members
those modules will need (`agents`, `activeStreams`, `mcpClient`,
`threadStore`, `approvalGate`, `resolvedApprovalPolicy`,
`resolvedLimits`, `countUserStreams`). All marked `@internal` to
keep the public surface unchanged.

Note: the full split into `routes/` and `tool-execution.ts` proposed
in plans/agent-architecture-followup.md is deferred. Route handlers
and `_streamAgent`/`runSubAgent` remain as methods on AgentsPlugin
because they have heavy plugin-state coupling and cross-call patterns
(`runSubAgent` recurses, `_handleChat` calls `_streamAgent`,
etc.) that don't translate cleanly to free functions without a larger
refactor. Tracked as a follow-up.

agents.ts: 1262 -> 1212 lines (-50). The plan's aspirational target
of <=280 isn't met because the per-route extraction pass is deferred,
but the helper extraction + access-modifier relaxation lays the
groundwork.

Verified: tsc --noEmit clean, 1589/1589 appkit tests pass.

…te manifest)

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

…ebase

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

PR #305 agentic-review fixes (P1 + cheap P2):

- _handleChat / _handleInvocations now wrap threadStore calls in
  try/catch and surface failures as a 500. Without this an unreachable
  store hung the SSE client until the upstream proxy timeout because
  the async Express handler propagated the rejection without a
  response.
- runAgent rejects hosted/MCP tools at index-build time with a clear
  pointer to createApp({ plugins: [..., agents()] }). Previously the
  adapter saw the tool list and the failure surfaced mid-conversation.
- Extract applyToolkitOptions: single source of truth for the
  prefix/only/except/rename filtering shared by build-toolkit (registry
  path) and toolkit-resolver (getAgentTools fallback). Bug fixes here
  apply to both paths instead of drifting between them.
- resolveStandaloneProvider now uses an isStandaloneToolProvider type
  guard instead of `instance as unknown as ToolProvider`. Distinct from
  core/plugin-context.isToolProvider which also requires asUser
  (request-scoped, only meaningful inside createApp).

Tests added:

- threadStore failure paths on /chat (get/create/addMessage rejections)
  and /invocations (create + addMessage mid-loop) — assert 500
  responses with the canonical error body.
- runAgent rejects hosted tools at standalone resolution.
- runAgent surfaces a clear error when fromPlugin references a plugin
  lacking ToolProvider methods.
- runAgent recursively executes sub-agents declared on def.agents.

#4 (countUserStreams O(n)) deferred — n bounded by 5 × users in the
default config; not a hot path. #11 (printRegistry console.log) and

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
#9-#15 advisory items left as-is per the PR-comment thread.

Drop the symbol-keyed fromPlugin(factory) API in favor of a function
form on AgentDefinition.tools that receives a typed plugins map. The
key win: each plugin appears exactly once in user code (only inside
createApp({ plugins: [...] })), and plugins.<name>.toolkit() is fully
autocompleted in the IDE.

Before:

  import { analytics, fromPlugin } from "@databricks/appkit";

  const support = createAgent({
    tools: { ...fromPlugin(analytics) },
  });
  await createApp({ plugins: [analytics(), agents({ agents: { support } })] });

After:

  const support = createAgent({
    tools(plugins) {
      return { ...plugins.analytics.toolkit() };
    },
  });
  await createApp({ plugins: [analytics(), agents({ agents: { support } })] });

The dual tools: AgentTools | AgentToolsFn shape means simple agents
keep the plain object form. The function runs once at agent setup; its
return record replaces def.tools for the rest of the registered
agent's lifetime.

Typing relies on a RegisteredPlugins module-augmentation interface that
core plugins (analytics, files, genie, lakebase) extend at their
declaration sites. Third-party plugins fall back to a
PluginToolkitProvider shape via the index signature; they still work at
runtime, just without keyed autocomplete.

Standalone runAgent invokes the function form against a Plugins map
built lazily from RunAgentInput.plugins. Plugin instances are
constructed on first plugins.<name>.toolkit() call and cached, so the
same instance handles both spread-time and dispatch-time work.

Auto-inherit semantics unchanged: declaring tools (object or function,
even an empty record) opts out, mirroring the prior rule.

Markdown agents are untouched. YAML cannot carry a function reference,
so toolkits: [analytics] and ambient agents({ tools: {...} }) keep
working as the markdown surface.

fromPlugin, FromPluginMarker, FROM_PLUGIN_MARKER, FromPluginSpread,
isFromPluginMarker, and the NamedPluginFactory.pluginName field
(its only consumer) are deleted from beta exports and from-plugin.ts.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

…ugin augmentation

Two follow-ups on the tools(plugins) function form:

1. Each entry in the Plugins map is now typed as PluginToolkitProvider
   (just the .toolkit() method) instead of the full plugin class. Inside
   tools(plugins), plugins.analytics.<TAB> shows only .toolkit() — the
   contract for tool composition — instead of leaking query, name,
   setup, injectRoutes, and every other instance method.

2. RegisteredPlugins ships pre-populated with the four core plugin keys
   (analytics, files, genie, lakebase) directly in core/agent/types.ts.
   The per-plugin "declare module ../../core/agent/types" blocks at the
   bottom of each core plugin file are gone. Adding a new core plugin
   now means adding one line to RegisteredPlugins, not duplicating an
   augmentation block.

Third-party plugins still augment RegisteredPlugins from user code if
they want their key in autocomplete; the index-signature fallback
keeps unaugmented names working at runtime.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

…ed record

Hardcoding the registered plugin names in core/agent/types.ts was the
wrong shape — AppKit cannot statically know which plugins the
surrounding createApp call will register, so a curated list there was
guaranteed to drift.

Drop the RegisteredPlugins augmentation interface entirely. Plugins is
now Record<string, PluginToolkitProvider>: every entry exposes
.toolkit() at runtime, but plugin names do not autocomplete inside
tools(plugins). Users refer to plugins by the same name they pass to
createApp({ plugins: [...] }).

Plugin-name autocomplete (so tools(plugins) sees plugins.<TAB> ->
analytics | files | ...) is a separate, larger design problem with
real tradeoffs across inline-in-createApp, factory pattern, codegen,
and user augmentation. Tracked separately; this commit unblocks the
v5 stack with a runtime-correct, honest type that does not lie about
what AppKit knows.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

countUserStreams() previously walked every entry in activeStreams on
every /chat and /invocations request — O(n) over total concurrent
streams across all users on the hot path. At scale that scan dominates
chat-request latency under load.

Add userStreamCounts: Map<string, number> kept in sync with
activeStreams via two new helpers:

- trackStream(requestId, userId, controller) — sole writer that
  registers a stream and increments the user's counter.
- untrackStream(requestId) — sole writer that removes a stream and
  decrements the counter; deletes the user's entry on the last stream
  to keep the map bounded across many distinct users; idempotent on
  unknown ids.

countUserStreams() is now an O(1) Map.get(). All three previous
mutation sites (_streamAgent setup, _streamAgent finally, _handleCancel)
go through the helpers, so the counter cannot drift from the map.

Tests: existing dos-limits seeders updated to use trackStream(); new
test in dos-limits.test.ts asserts the invariant across track/untrack
for multiple users plus idempotent untrack.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Address all four medium findings from the xavier review panel
(correctness + security + performance) on PR #305.

1. applyToolkitOptions no longer returns literal "undefined"

   The rename branch used Object.hasOwn(rename, name) followed by an
   unguarded rename[name] return. When a developer wrote
   `rename: { query: featureFlag ? "x" : undefined }`, the explicit
   undefined satisfied hasOwn() and propagated as the toolkit key,
   producing a tool keyed literally "undefined" downstream.

   Drop hasOwn, use nullish coalescing + empty-string guard so explicit
   undefined and "" both fall through to the prefix path. Adds a new
   toolkit-options.test.ts covering all four knobs (prefix, only,
   except, rename) plus the regression case.

2. runAgent shares providerCache across sub-agent recursion

   Sub-agent tool dispatch used to call runAgent recursively, which
   built a fresh providerCache inside buildStandaloneToolIndex on every
   nested call. Plugins were re-instantiated per sub-agent invocation,
   in-instance state diverged between parent and child, and any
   per-call setup cost (pool open, client construction) ran for every
   nested level.

   Hoist the cache to the top-level runAgent and thread it through a
   private runAgentInternal() helper so all nested calls share the
   same instance map.

3. Plugin lookup names the missing plugin (proxy)

   The Plugins type is Record<string, PluginToolkitProvider> without
   noUncheckedIndexedAccess workspace-wide, so unknown keys typecheck
   as present but resolve to undefined at runtime. Accessing
   .toolkit() on undefined produced a generic
   "Cannot read properties of undefined (reading 'toolkit')" with no
   plugin name and no list of available plugins.

   New core/agent/plugins-map.ts exports createPluginsProxy() — wraps
   the resolved record so unknown string-key access throws a named
   error: "<context> referenced plugin '<name>', but it is not
   registered. Available: ...". Used by both standalone runAgent and
   the agents plugin's buildPluginsMap. Symbol access and well-known
   probes (then, toJSON, toString, valueOf, constructor) pass through
   untouched so Promise/JSON tooling doesn't trip the guard.

4. Standalone runAgent eagerly initialises plugin lifecycle

   resolveStandaloneProvider used to construct plugin instances lazily
   on first plugins[name].toolkit() call and never invoke
   attachContext()/setup(). First-party plugins like AnalyticsPlugin
   that depend on createApp's runtime (WorkspaceClient,
   ServiceContext, PluginContext) crashed mid-stream when their tools
   dereferenced getWorkspaceClient(), with stack traces far from the
   cause. The previous JSDoc only hinted with "(when they work at
   all)".

   New initStandalonePlugins() helper runs at the top of runAgent:
   constructs every plugin in input.plugins, calls attachContext({}),
   awaits setup(), and populates the shared cache. Failures wrap with
   a clear message naming the plugin and pointing the caller at
   createApp({ plugins: [..., agents(...)] }). Plugins with the
   default no-op setup() initialise cleanly; plugins that need
   createApp-only runtime fail at startup, not mid-conversation.

   The runAgent JSDoc is rewritten to spell out the trust boundary
   (no OBO, no approval gate, treat as trusted-prompt environment)
   and the new init contract.

Tests: + 8 toolkit-options unit tests, + 3 run-agent tests covering
the new behaviours (proxy names missing plugin, setup failure
surfaces at entry not mid-stream, sub-agent recursion shares plugin
instance with parent — verified by counting constructor calls and
asserting same instance id from both parent and child tools). 2284
tests passing across the workspace.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>